home *** CD-ROM | disk | FTP | other *** search
/ Amiga Collections: Tampa Bay Amiga Group / TBAG - Tampa Bay Amiga Group's Disk of the Month #51 (1991)(Merlin's Software - Amiganuts United)(PD).zip / TBAG - Tampa Bay Amiga Group's Disk of the Month #51 (1991)(Merlin's Software - Amiganuts United)(PD).adf / Docs / STV.docs < prev    next >
Text File  |  1991-01-08  |  10KB  |  285 lines
  1.                   ***************************************
  2.                   *                                     *
  3.                   *   STV - Simple Text Viewer v1.00a   *
  4.                   *   © Copyright 1990 by Timm Martin   *
  5.                   *                                     *
  6.                   ***************************************
  7.  
  8.  
  9. This program is freeware.  It may be distributed alone or in conjunction with
  10. any program, commercial or otherwise, with no compensation to the author.
  11.  
  12.  
  13. ******************
  14. *  INTRODUCTION  *
  15. ******************
  16.  
  17. As the name implies, STV is a very simple text viewer.  It does not:
  18.  
  19.   -- display ANSI codes
  20.   -- use blitter text for high-speed scrolling
  21.   -- have word wrap or scroll horizontally
  22.  
  23. However, STV:
  24.  
  25.   -- has word search
  26.   -- has the ability to read multiple documents
  27.   -- runs from an icon (Workbench)
  28.   -- runs on the Workbench or ANY custom screen
  29.   -- allows you to specify its position and size
  30.   -- accommodates both mouse and keyboard input
  31.   -- works great with Workbench v2.0 (and v1.3) and all custom fonts
  32.  
  33. The main purpose of this program is to display program docs and README files.
  34. Because you can specify the window specifications in the icon's ToolTypes,
  35. STV is perfect for PD and computer club disks.  STV also has a programming
  36. hook that allows you to call it from within your program and use it as a file
  37. viewer.
  38.  
  39.  
  40. ****************
  41. *  PARAMETERS  *
  42. ****************
  43.  
  44. You can specify five parameters when running STV:
  45.  
  46.   LeftEdge
  47.     The left edge of the STV window.  This is relative to the screen in which
  48.     it will appear.  The default is 0.
  49.  
  50.   TopEdge
  51.     The top edge of the STV window.  This is relative to the screen in which
  52.     it will appear.  The default is 2.  This gives you access to the screen's
  53.     depth gadgets.
  54.  
  55.   Width
  56.     The width of the STV window in pixels.  The default is the maximum width
  57.     of the screen.
  58.  
  59.   Height
  60.     The height of the STV window in pixels.  The default is the maximum
  61.     height of the screen.
  62.  
  63.   TextColor
  64.     The color of the text in the STV window.  The default is pen number 1,
  65.     which is normally white under Workbench v1.x and black under WB v2.x.
  66.     This option is provided for programs which call STV and may operate
  67.     under different versions of the operating system or which will open the
  68.     STV window on its own custom screen and wants to control the text color.
  69.  
  70.   Screen
  71.     The DECIMAL address of the screen in which STV will appear.  CAUTION!
  72.     STV does not verify that this address is valid.  If you specify an
  73.     invalid address, the system will likely crash.  If no screen address is
  74.     provided, STV will open its window on the Workbench screen.
  75.  
  76. STV will not allow you to specify an invalid LeftEdge, TopEdge, Width, or
  77. Height.  It will try to accommodate your specifications as best as possible.
  78.  
  79.  
  80. *************************
  81. *  TO RUN FROM THE CLI  *
  82. *************************
  83.  
  84. To run STV from the CLI, type:
  85.  
  86.   STV [parameters] file1 [file2...]
  87.  
  88. where the parameters are:
  89.  
  90.   -c<number> ... TextColor
  91.   -h<number> ... Height
  92.   -l<number> ... LeftEdge
  93.   -t<number> ... TopEdge
  94.   -w<number> ... Width
  95.   -!<number> ... Screen
  96.  
  97. The parameter characters c,h,l,t,w may be either upper or lower case.  The
  98. parameters must be preceeded by a hyphen so that STV knows they are not file
  99. names.  Each parameter must be followed by the corresponding number.
  100. Embedded blanks are not permitted.
  101.  
  102. Note that you can specify more than one file name.  If the desired file is
  103. not in the current directory, be sure to specify its complete path as well.
  104. File names with embedded blanks should be enclosed in quotes.
  105.  
  106. Parameters and file names may be mixed up in any order.
  107.  
  108. For example:
  109.  
  110.   stv s:shell-startup -c2 -h120 -L45 -!237890 -T16 -w400 readme
  111.  
  112. will open a 400 x 120 pixel STV window at location 45,16 in the custom screen
  113. whose address is decimal 237890 and load the "shell-startup" file in the s:
  114. directory and the "readme" file in the current directory and whose text is
  115. displayed with pen number 2.
  116.  
  117.  
  118. ***************************
  119. *  TO RUN FROM WORKBENCH  *
  120. ***************************
  121.  
  122. Create a project icon for the text files you want to read (you can copy the
  123. icon used for this file if you like).  Click on the icon once to highlight
  124. it.  Select "Info" from the Workbench menu.  Enter the name "STV" in the
  125. "Default Tool" field.  If you place STV in a different directory such as c:,
  126. be sure to specify the entire path name such as "c:stv".
  127.  
  128. You can specify the parameters listed above by adding Tool Types.  The
  129. following tool types are accepted:
  130.  
  131.   COLOR= .... TextColor
  132.   HEIGHT= ... Height
  133.   LEFT= ..... LeftEdge
  134.   TOP= ...... TopEdge
  135.   WIDTH= .... Width
  136.  
  137. There is no tool type for the Screen.  Note that the tool types must be in
  138. capital letters (this restiction has been lifted under WB 2.0) and must be
  139. followed immediately by an equal sign.
  140.  
  141. As an example, the following tool types:
  142.  
  143.   HEIGHT=80
  144.   TOP=100
  145.   WIDTH=400
  146.  
  147. will open a 400 x 80 pixel screen at location 0,100 (0 is the default left
  148. edge as listed above).
  149.  
  150. To read more than one file at a time from the Workbench, click on all of the
  151. corresponding icons and select "Open" from the Workbench menu.  The files will
  152. be loaded in the order you clicked their icons.
  153.  
  154.  
  155. ***************
  156. *  OPERATION  *
  157. ***************
  158.  
  159. STV can be operated from the keyboard or with the mouse.
  160.  
  161.  
  162. SCROLLING THE DISPLAY
  163.  
  164.   UpArrow key ........... scroll up one line, displaying the previous line
  165.   DownArrow key ......... scroll down one line, displaying the next line
  166.   Alt-UpArrow key ....... scroll up one page, displaying the previous page
  167.   Alt-DownArrow key ..... scroll down one page, displaying the next page
  168.   Shift-UpArrow key ..... display beginning of file
  169.   Shift-DownArrow key ... display end of file
  170.  
  171.   As with the program "More", the Space Bar will also scroll down one page,
  172.   displaying the next page.
  173.  
  174.   You can also scroll the display by clicking the left mouse button on the
  175.   slider bar in the right edge of the window.  If you click on the bar and
  176.   hold down the left mouse button, the display will scroll with the movement
  177.   of the mouse.  Clicking above the bar will scroll the display up one page;
  178.   clicking below the bar will scroll the display down one page.
  179.  
  180.   You can also scroll the display by clicking the left mouse button anywhere
  181.   else in the window.  Clicking and holding the left mouse button while the
  182.   mouse pointer is above the center of the window will cause the display to
  183.   scroll up one line at a time.  Clicking below the center of the window will
  184.   cause the display to scroll down one line at a time.  As you move the mouse
  185.   closer to the center of the window, the scrolling will slow down.  The
  186.   farther away from the center the pointer is, the faster the display will
  187.   scroll.  If you move the pointer to the top or above the window, the
  188.   display will begin to page backward.  If you move the pointer to the bottom
  189.   or below the window, the display will page forward.
  190.  
  191.  
  192. FILE SELECTION
  193.  
  194.   STV loads and displays only one file at a time and in the order you
  195.   specify them.  To display the next file, press the 'N' key or select "Next
  196.   File" from the menu.  To display the previous file, press the 'P' key or
  197.   select "Previous File" from the menu.  These menu options will be disabled
  198.   (ghosted) if there are no previous or next files to display.
  199.  
  200.  
  201. WORD SEARCH
  202.  
  203.   To search for a word in the displayed file, select "Search" from the menu
  204.   or press the 'S' key.  The prompt "Search for:" and a cursor will appear in
  205.   the middle of the STV window.  Type up to 20 characters and press RETURN.
  206.   The normal Amiga string gadget commands are available here:  Right-Amiga-X
  207.   to delete the contents, etc.  To cancel the search, delete the contents and
  208.   press RETURN.
  209.  
  210.   The search is case insensitive, meaning that the search string "program"
  211.   will find "Program", "PROGRAM", and "programming".  Of course, you can also
  212.   include embedded blanks to search for a phrase, such as "C Programming".
  213.  
  214.   STV will always start its search from the beginning of the file and will
  215.   search forward.  If the string of words you entered is found, STV will
  216.   display the string at the top of the window and will highlight the string.
  217.   If the string is not found, the display will flash.
  218.  
  219.   To continue searching from the current search position (in other words,
  220.   from the point where the last search word was found), select "Search Again"
  221.   from the menu or press the 'A', RETURN, or ENTER key.
  222.  
  223.   NOTE: Searching in binary files will not work correctly.
  224.  
  225.  
  226. LET ME OUTTA HERE!
  227.  
  228.   To quit the program, select "Quit" from the menu or press the 'Q' or ESCape
  229.   key.  You don't have to read all of the specified files to quit.
  230.  
  231.  
  232. ***************************
  233. *  TECHNICAL INFORMATION  *
  234. ***************************
  235.  
  236. To open the STV window on a custom screen from within a C program, consider
  237. the following example:
  238.  
  239.   /* using these variable definitions */
  240.   char buffer[100];       /* a scratch buffer for use with Execute() */
  241.   char *file_name;        /* contains the name of the file to be displayed */
  242.   struct Screen *screen;  /* pointer to an opened custom screen */
  243.  
  244.   /* use this code to run STV */
  245.   sprintf( buffer, "c:STV -!%ld %s", (long)screen, file_name );
  246.   Execute( buffer, NULL, NULL );
  247.  
  248. See the AmigaDOS docs for more information on how to use the Execute()
  249. command.  It's often not quite as simple as listed above.  If you want STV to
  250. run asynchronously (in other words, you don't want your program to "sleep"
  251. while STV is running), add the "run" command before "c:STV".
  252.  
  253.  
  254. ****************
  255. *  THE FUTURE  *
  256. ****************
  257.  
  258. This program is about as simple as you can get.  I suppose someday I may
  259. attempt to write "the ultimate text reader," but right now I really have no
  260. idea just what that would be.  Have any suggestions?  Then let me know.
  261.  
  262.  
  263. *************
  264. *  UPDATES  *
  265. *************
  266.  
  267. v1.00  09/28/90 - Original release
  268. v1.00a 12/31/90 - Added TextColor option
  269.  
  270.  
  271. ********************
  272. *  CORRESPONDENCE  *
  273. ********************
  274.  
  275.   Timm Martin
  276.   P.O. Box 10084
  277.   Largo, FL  34643
  278.   U.S.A.
  279.  
  280.  
  281. STV Docs v1.00a 12/31/90
  282. © Copyright 1990 Timm Martin
  283.  
  284. /*-- END --*/
  285.